.TH std::istreambuf_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::istreambuf_iterator \- std::istreambuf_iterator

.SH Synopsis
   Defined in header <iterator>
   template< class CharT, class Traits = std::char_traits<CharT> >

   class istreambuf_iterator
       : public std::iterator<std::input_iterator_tag,              \fI(until C++17)\fP
                              CharT, typename Traits::off_type,

                              /* unspecified */, CharT>
   template< class CharT, class Traits = std::char_traits<CharT> >  \fI(since C++17)\fP
   class istreambuf_iterator;

   std::istreambuf_iterator is a single-pass input iterator that reads successive
   characters from the std::basic_streambuf object for which it was constructed.

   The default-constructed std::istreambuf_iterator is known as the end-of-stream
   iterator. When a valid std::istreambuf_iterator reaches the end of the underlying
   stream, it becomes equal to the end-of-stream iterator. Dereferencing or
   incrementing it further invokes undefined behavior.

   std::istreambuf_iterator has a trivial copy constructor, a constexpr   \fI(since C++11)\fP
   default constructor, and a trivial destructor.

.SH Member types

   Member type       Definition
   iterator_category std::input_iterator_tag
   value_type        CharT
   difference_type   typename Traits::off_type
   pointer           /* unspecified */
   reference         CharT
   char_type         CharT
   traits_type       Traits
   int_type          typename Traits::int_type
   streambuf_type    std::basic_streambuf<CharT, Traits>
   istream_type      std::basic_istream<CharT, Traits>
                     Implementation-defined class type. The name proxy is for
                     exposition only.
   /* proxy */       A proxy object holds a char_type character and a streambuf_type*
                     pointer.
                     Dereferencing a proxy object with operator* yields the stored
                     character.

   Member types iterator_category, value_type, difference_type, pointer
   and reference are required to be obtained by inheriting from           \fI(until C++17)\fP
   std::iterator<std::input_iterator_tag, CharT, typename
   Traits::off_type, /* unspecified */, CharT>.

   The member type pointer is usually CharT* (see below).

.SH Member functions

   constructor           constructs a new istreambuf_iterator
                         \fI(public member function)\fP
   destructor            destructs an istreambuf_iterator
   (implicitly declared) \fI(public member function)\fP
   operator*             obtains a copy of the current character
                         \fI(public member function)\fP
   operator++            advances the iterator
   operator++(int)       \fI(public member function)\fP
                         tests if both istreambuf_iterators are end-of-stream or if
   equal                 both are valid
                         \fI(public member function)\fP

.SH Non-member functions

   operator==         compares two istreambuf_iterators
   operator!=         \fI(function template)\fP
   (removed in C++20)

.SH Notes

   The resolution of LWG issue 659 introduced operator->. It is expected that given an
   std::istreambuf_iterator i, the expressions (*i).m and i->m have the same effect.

   However, the resolution does not provide a formal specification of its behavior.
   Thus it is implemented differently, including returning nullptr, returning the
   address of a temporary, or does even provide the member at all. Its intended
   behavior can hardly be achieved, and it is removed by the resolution of LWG issue
   2790.

   The resolution of LWG issue 659 also made the member type pointer unspecified in
   order to allow operator-> to return a proxy. This is to allow operator-> to compile
   when CharT is not a class type.

.SH Example


// Run this code

 #include <iostream>
 #include <iterator>
 #include <sstream>
 #include <string>

 int main()
 {
     // typical use case: an input stream represented as a pair of iterators
     std::istringstream in{"Hello, world"};
     std::istreambuf_iterator<char> it{in}, end;
     std::string ss{it, end};
     std::cout << "ss has " << ss.size() << " bytes; "
                  "it holds \\"" << ss << "\\"\\n";

     // demonstration of the single-pass nature
     std::istringstream s{"abc"};
     std::istreambuf_iterator<char> i1{s}, i2{s};
     std::cout << "i1 returns '" << *i1 << "'\\n"
                  "i2 returns '" << *i2 << "'\\n";

     ++i1;
     std::cout << "after incrementing i1, but not i2:\\n"
                  "i1 returns '" << *i1 << "'\\n"
                  "i2 returns '" << *i2 << "'\\n";

     ++i2;
     std::cout << "after incrementing i2, but not i1:\\n"
                  "i1 returns '" << *i1 << "'\\n"
                  "i2 returns '" << *i2 << "'\\n";
 }

.SH Output:

 ss has 12 bytes; it holds "Hello, world"
 i1 returns 'a'
 i2 returns 'a'
 after incrementing i1, but not i2:
 i1 returns 'b'
 i2 returns 'b'
 after incrementing i2, but not i1:
 i1 returns 'c'
 i2 returns 'c'

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to            Behavior as published              Correct behavior
                       1. std::istreambuf_iterator did not have
   LWG 659  C++98      operator->                                   1. added
                       2. the member type pointer was specified as  2. made unspecified
                       CharT*
   LWG 2790 C++98      the operator-> added by LWG issue 659 was    removed
                       not useful

.SH See also

   ostreambuf_iterator output iterator that writes to std::basic_streambuf
                       \fI(class template)\fP
   istream_iterator    input iterator that reads from std::basic_istream
                       \fI(class template)\fP
